'\" t
.\"     Title: pyang
.\"    Author: Martin Bjorklund <mbj@tail-f.com>
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 2010-10-07
.\"    Manual: pyang manual
.\"    Source: pyang-1.0
.\"  Language: English
.\"
.TH "PYANG" "1" "2010\-10\-07" "pyang\-1\&.0" "pyang manual"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pyang \- validate and convert YANG modules to various formats
.SH "SYNOPSIS"
.HP \w'\fBpyang\fR\ 'u
\fBpyang\fR [\-\-canonical] [\-\-strict] [\-\-ietf] [\-o\ \fIoutfile\fR] [\-f\ \fIformat\fR] [\-p\ \fIpath\fR] [\-W\ \fIwhat\fR] \fImodule\fR...
.HP \w'\fBpyang\fR\ 'u
\fBpyang\fR [\-h | \-\-help]
.HP \w'\fBpyang\fR\ 'u
\fBpyang\fR [\-v | \-\-version]
.PP
If no files are given,
\fBpyang\fR
reads one module from stdin\&.
.PP
Only the most common options are listed here\&. See below for a complete list of options\&.
.SH "DESCRIPTION"
.PP
The
\fBpyang\fR
program is used to validate YANG modules (RFC 6020)\&. It is also used to convert YANG modules into equivalent YIN modules\&. From a valid module, a W3C XML Schema (XSD) or hybrid DSDL schema (RELAX NG with additional annotations) can be generated\&.
.PP
If no
\fIformat\fR
is given, the specified modules are validated, and the program exits with exit code 0 if all modules are valid\&.
.SH "OPTIONS"
.PP
\fB\-h\fR \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-v\fR \fB\-\-version\fR
.RS 4
Print the version number and exit\&.
.RE
.PP
\fB\-e\fR \fB\-\-list\-errors\fR
.RS 4
Print a listing of all error codes and messages pyang might generate, and then exit\&.
.RE
.PP
\fB\-\-print\-error\-code\fR
.RS 4
On errors, print the symbolic error code instead of the error message\&.
.RE
.PP
\fB\-Werror\fR
.RS 4
Treat warnings as errors\&.
.RE
.PP
\fB\-Wnone\fR
.RS 4
Do not print any warnings\&.
.RE
.PP
\fB\-\-canonical\fR
.RS 4
Validate the module(s) according to the canonical YANG order\&.
.RE
.PP
\fB\-\-strict\fR
.RS 4
Force strict YANG compliance\&. Currently this checks that the deref() function is not used in XPath expressions and leafrefs\&.
.RE
.PP
\fB\-\-ietf\fR
.RS 4
Validate the module(s) according to IETF rules as specified in draft\-ietf\-netmod\-yang\-usage\&. In addition, it checks that the module is in canonical order, and that
\fB\-\-max\-line\-length\fR
is 72 so that the module fits into an RFC\&.
.RE
.PP
\fB\-\-trim\-yin\fR
.RS 4
In YIN input modules, remove leading and trailing whitespace from every line in the arguments of the following statements: \'contact\', \'description\', \'error\-message\', \'organization\' and \'reference\'\&. This way, the XML\-indented argument texts look tidy after translating the module to the compact YANG syntax\&.
.RE
.PP
\fB\-\-max\-line\-length\fR \fImaxlen\fR
.RS 4
Give a warning if any line is longer than
\fImaxlen\fR\&.
.RE
.PP
\fB\-\-max\-identifier\-length\fR \fImaxlen\fR
.RS 4
Give a error if any identifier is longer than
\fImaxlen\fR\&.
.RE
.PP
\fB\-f\fR \fB\-\-format\fR \fIformat\fR
.RS 4
Convert the module(s) into
\fIformat\fR\&. Some translators require a single module, and some can translate multiple modules at one time\&. If no
\fIoutfile\fR
file is specified, the result is printed on stdout\&. The supported formats are listed in
OUTPUT FORMATS
below\&.
.RE
.PP
\fB\-o\fR \fB\-\-output\fR \fIoutfile\fR
.RS 4
Write the output to the file
\fIoutfile\fR
instead of stdout\&.
.RE
.PP
\fB\-p\fR \fB\-\-path\fR \fIpath\fR
.RS 4

\fIpath\fR
is a colon (:) separated list of directories to search for imported modules\&. This option may be given multiple times\&.
.sp
The following directories are always added to the search path:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
current directory
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}

\fB$YANG_MODPATH\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}

\fB$HOME\fR/yang/modules
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}

\fB$YANG_INSTALL\fR/yang/modules
OR if
\fB$YANG_INSTALL\fR
is unset
<the default installation directory>/yang/modules
(on Unix systems:
/usr/share/yang/modules)
.RE
.RE
.PP
\fB\-\-plugindir\fR \fIplugindir\fR
.RS 4
Load all YANG plugins found in the directory
\fIplugindir\fR\&. This option may be given multiple times\&.
.sp
list of directories to search for pyang plugins\&. The following directories are always added to the search path:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}

pyang/plugins
from where pyang is installed
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}

\fB$PYANG_PLUGINPATH\fR
.RE
.RE
.PP
\fImodule\&.\&.\&.\fR
.RS 4
These are the names of the files containing the modules to be validated, or the module to be converted\&.
.RE
.SH "OUTPUT FORMATS"
.PP
If pyang plugins are installed, these plugins may define their own options, or add new formats to the
\fB\-f\fR
option\&. These options and formats are listed in
\fBpyang \-h\fR\&.
.PP
\fIyin\fR
.RS 4
the XML syntax of YANG
.RE
.PP
\fIyang\fR
.RS 4
normal YANG syntax
.RE
.PP
\fIdsdl\fR
.RS 4
Hybrid DSDL schema (RELAX NG with annotations)
.RE
.PP
\fIxsd\fR
.RS 4
W3C XML Schema
.RE
.PP
\fIdepend\fR
.RS 4
Prints a Makefile dependency rule for the module
.RE
.PP
\fItree\fR
.RS 4
tree structure of the module
.RE
.SH "YANG OUTPUT"
.PP
Options for the
\fIyang\fR
output format:
.PP
\fB\-\-yang\-canonical\fR
.RS 4
Generate all statements in the canonical order\&.
.RE
.SH "YIN OUTPUT"
.PP
Options for the
\fIyin\fR
output format:
.PP
\fB\-\-yin\-canonical\fR
.RS 4
Generate all statements in the canonical order\&.
.RE
.PP
\fB\-\-yin\-pretty\-strings\fR
.RS 4
Pretty print strings, i\&.e\&. print with extra whitespace in the string\&. This is not strictly correct, since the whitespace is significant within the strings in XML, but the output is more readable\&.
.RE
.SH "DSDL OUTPUT"
.PP
Options for the
\fIdsdl\fR
output format:
.PP
\fB\-\-dsdl\-no\-documentation\fR
.RS 4
Do not print documentation annotations
.RE
.PP
\fB\-\-dsdl\-no\-dublin\-core\fR
.RS 4
Do not print Dublin Core metadata terms
.RE
.PP
\fB\-\-dsdl\-record\-defs\fR
.RS 4
Record translations of all top\-level typedefs and groupings in the output schema, even if they are not used\&. This is useful for translating library modules\&.
.RE
.SH "XSD OUTPUT"
.PP
Options for the
\fIxsd\fR
output format:
.PP
\fB\-\-xsd\-no\-appinfo\fR
.RS 4
Do not print YANG specific appinfo\&.
.RE
.PP
\fB\-\-xsd\-no\-lecture\fR
.RS 4
Do not print the lecture about how the XSD can be used\&.
.RE
.PP
\fB\-\-xsd\-no\-imports\fR
.RS 4
Do not generate any xs:imports\&.
.RE
.PP
\fB\-\-xsd\-no\-includes\fR
.RS 4
Do not generate any xs:includes\&.
.RE
.PP
\fB\-\-xsd\-break\-pattern\fR
.RS 4
Break long patterns so that they fit into RFCs\&. The resulting patterns might not always be valid XSD, so use with care\&.
.RE
.SH "DEPEND OUTPUT"
.PP
The
\fIdepend\fR
output generates a Makefile dependency rule for files based on a YANG module\&. This is useful if files are generated from the module\&. For example, suppose a \&.c file is generated from each YANG module\&. If the YANG module imports other modules, or includes submodules, the \&.c file needs to be regenerated if any of the imported or included modules change\&. Such a dependency rule can be generated like this:
.sp
.if n \{\
.RS 4
.\}
.nf
$ pyang \-f depend \-\-depend\-target mymod\&.c \e
    \-\-depend\-extension \&.yang mymod\&.yang
mymod\&.c : ietf\-yang\-types\&.yang my\-types\&.yang
.fi
.if n \{\
.RE
.\}
.PP
Options for the
\fIdepend\fR
output format:
.PP
\fB\-\-depend\-target\fR
.RS 4
Makefile rule target\&. Default is the modulename\&.
.RE
.PP
\fB\-\-depend\-extension\fR
.RS 4
YANG module file name extension\&. Default is no extension\&.
.RE
.PP
\fB\-\-depend\-no\-submodules\fR
.RS 4
Do not generate dependencies for included submodules\&.
.RE
.SH "TREE OUTPUT"
.PP
The
\fItree\fR
output prints the resulting schema tree from one or more modules\&. Use
\fBpyang \-\-tree\-help\fR
to print a description on the symbols used by this format\&.
.PP
Tree output specific option:
.PP
\fB\-\-tree\-help\fR
.RS 4
Print help on symbols used in the tree output and exit\&.
.RE
.SH "YANG EXTENSIONS"
.PP
This section describes XPath functions that can be used in "must", "when", or "path" expressions in YANG modules, in addition to the core XPath 1\&.0 functions\&.
.PP

\fBpyang\fR
can be instructed to reject the usage of these functions with the parameter
\fI\-\-strict\fR\&.
.PP

\fBFunction:\fR
\fInode\-set\fR
\fBderef\fR(\fInode\-set\fR)
.PP
The
\fBderef\fR
function follows the reference defined by the first node in document order in the argument node\-set, and returns the nodes it refers to\&.
.PP
If the first argument node is an
\fBinstance\-identifier\fR, the function returns a node\-set that contains the single node that the instance identifier refers to, if it exists\&. If no such node exists, an empty node\-set is returned\&.
.PP
If the first argument node is a
\fBleafref\fR, the function returns a node\-set that contains the nodes that the leafref refers to\&.
.PP
If the first argument node is of any other type, an empty node\-set is returned\&.
.PP
The following example shows how a leafref can be written with and without the
\fBderef\fR
function:
.sp
.if n \{\
.RS 4
.\}
.nf
/* without deref */

leaf my\-ip {
    type leafref {
        path "/server/ip";
    }
}
leaf my\-port {
    type leafref {
        path "/server[ip = current()/\&.\&./my\-ip]/port";
    }
}

/* with deref */

leaf my\-ip {
    type leafref {
        path "/server/ip";
    }
}
leaf my\-port {
    type leafref {
        path "deref(\&.\&./my\-ip)/\&.\&./port";
    }
}
      
.fi
.if n \{\
.RE
.\}
.SH "EXAMPLE"
.PP
The following example validates the standard YANG modules with derived types:
.sp
.if n \{\
.RS 4
.\}
.nf
$ pyang ietf\-yang\-types\&.yang ietf\-inet\-types\&.yang
.fi
.if n \{\
.RE
.\}
.PP
The following example converts the ietf\-yang\-types module into YIN:
.sp
.if n \{\
.RS 4
.\}
.nf
$ pyang \-f yin \-o ietf\-yang\-types\&.yin ietf\-yang\-types\&.yang
.fi
.if n \{\
.RE
.\}
.SH "ENVIRONMENT VARIABLES"
.PP
pyang searches for referred modules in the colon (:) separated path defined by the environment variable
\fB$YANG_MODPATH\fR
and in the directory
\fB$YANG_INSTALL\fR/yang/modules\&.
.PP
pyang searches for plugins in the colon (:) separated path defined by the environment variable
\fB$PYANG_PLUGINDIR\fR\&.
.SH "BUGS"
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
The XPath arguments for the
\fImust\fR
and
\fIwhen\fR
statements are checked only for basic syntax errors\&.
.RE
.SH "AUTHORS"
.PP
\fBMartin Bjorklund\fR <\&mbj@tail\-f\&.com\&>
.br
Tail\-f Systems
.RS 4
.RE
.PP
\fBLadislav Lhotka\fR <\&lhotka@cesnet\&.cz\&>
.br
CESNET
.RS 4
.RE
